import Highlight from '@site/src/components/Highlight';

- Type: <Highlight> SandboxConfig | false </Highlight>可选，默认值为 [全局 sandbox 配置](/api/run#sandbox)，当设置为 false 时关闭沙箱；

- SandboxConfig：

```ts
interface SandboxConfig {
  // 是否开启快照沙箱，默认值为 false：关闭快照沙箱，开启 vm 沙箱
  snapshot?: boolean;
  // 是否自动以子应用入口的域名前缀对子应用 fetch 请求的进行补齐，默认值为 false
  fixBaseUrl?: boolean;
  // 是否自动以子应用入口的域名前缀对相对路径资源进行前缀修正，默认值为 true，v1.15.0 版本提供
  fixStaticResourceBaseUrl?: boolean;
  // 是否开启开启严格隔离，默认值为 false。开启严格隔离后，子应用的渲染节点将会开启 Shadow DOM close 模式，并且子应用的查询和添加行为仅会在 DOM 作用域内进行
  strictIsolation?: boolean;
  // modules 仅在 vm 沙箱时有效，用于覆盖子应用执行上下文的环境变量，使用自定义的执行上下文，默认值为[]
  modules?: Array<Module> | Record<string, Module>;
  // disableElementtiming 1.14.4 版本提供，默认值为 false，将会给子应用元素注入 elementtiming 属性，可以通过此属性获取子应用元素的加载时间
  disableElementtiming?: boolean;
  // fixOwnerDocument  1.17.2 版本提供 ，默认值 false，目前可能会存在 ownerDocument 逃逸的情况，设置为 true 之后将会避免 ownerDocument 逃逸
  fixOwnerDocument?: boolean;
  // disableLinkTransformToStyle  1.18.0 版本提供 ，默认值 false，禁用掉 link 自动 transform 成 style 的行为
  disableLinkTransformToStyle?: boolean;
  // excludeAssetFilter 1.18.0 版本提供，默认值为 undefined，用于过滤不需要再子应用沙箱中执行的资源例如 jsonp，url 参数为对应 script 的地址，返回 true 则会过滤掉该资源
  excludeAssetFilter?: (url: string) => boolean;
}

type Module = (sandbox: Sandbox) => OverridesData | void;

export interface OverridesData {
  recover?: (context: Sandbox['global']) => void;
  prepare?: () => void;
  created?: (context: Sandbox['global']) => void;
  override?: Record<PropertyKey, any>;
}
```

- 示例

```ts
Garfish.run({
  sandbox: {
    snapshot: false,
    strictIsolation: false,
    // 覆盖子应用 localStorage，使用当前主应用 localStorage
    modules: [
      () => ({
        override: {
          localStorage: window.localStorage,
        },
      }),
    ],
  },
});
```

:::caution
请注意：
如果你在沙箱内自定义的行为将会产生副作用，请确保在 recover 函数中清除你的副作用，garfish 将在应用卸载过程中执行 recover 函数销毁沙箱副作用，否则可能会造成内存泄漏。
:::

- 在什么情况下我应该关闭 sandbox ?

  > Garfish 目前已默认支持沙箱 esModule 能力，若需要在 vm 沙箱支持 esModule 应用，请使用 `@garfish/es-module` garfish 官方插件支持此能力，但这会带来严重的性能问题，[原因](/issues/#esmodule)。如果你的项目不是很需要在 vm 沙箱下运行，此时可以关闭沙箱；

- [Garfish 沙箱机制](/guide/sandbox)

:::info
若开启快照沙箱，请注意：

1. 快照沙箱无法隔离主、子应用
2. 快照沙箱无法支持多实例（同时加载多个子应用）
   :::
